Collection of Tools & Utilities/Collection of Tools and Utilities.iso/c/gifsave.zip/gifsave.doc

Text File | 1992-09-26 | 11KB | 363 lines

                                      G I F S A V E


                         C-functions to save an image using GIF




                                  Written 26/9-1992 by

                                    Sverre H. Huseby
                                     Bjoelsengt. 17
                                       N-0468 Oslo
                                         Norway

                                   Phone: [phone]

                                   [e-mail]









          GIFSAVE reference                                       PAGE 2




                                      INTRODUCTION
                                      ============


          The GIFSAVE functions (hereafter called GIFSAVE) make it possible
          to save GIF-images from your own graphic-producing C-programs.

              The Graphics Interchange Format(c) is the Copyright property of
              CompuServe Incorporated. GIF(tm) is a Service Mark property of
              CompuServe Incorporated.

          (According to CompuServe Inc, the above note must be included in
          documentation of programs using GIF-files.)

          GIFSAVE creates simple GIF-files following the GIF87a standard.
          Interlaced images can not be created, and there should only be one
          image pr file.

          GIFSAVE is hereby dedicated to the Public Domain. Feel free to
          change the source code as you wish !!!










          GIFSAVE reference                                       PAGE 3




                                      USING GIFSAVE
                                      =============


          GIFSAVE consists of four functions, all decleared in GIFSAVE.H:

              GIF_Create() creates new GIF-files. It takes parameters
                  specifying the filename, screen size, number of colors, and
                  color resolution.

              GIF_SetColor() sets up the red, green and blue color
                  components. It should be called once for each possible
                  color.

              GIF_CompressImage() performs the compression of the image. It
                  accepts parameters describing the position and size of the
                  image on screen, and a user defined callback function that
                  is supposed to fetch the pixel values.

              GIF_Close() terminates and closes the file.

          The functions should be called in the listed order for each
          GIF-file. One file must be closed before a new one can be created.


          To use these functions, you must create a callback function that
          will do what is needed to get the pixel values for each point in
          the image.





                                       PORTABILITY
                                       ===========


          GIFSAVE is written using streams only, and all word (16 bits)
          outputs are split into byte outputs to force the byte swapping
          required in GIF-files. This should make the functions rather
          portable.

          File output is done through the functions Create(), Write(),
          WriteByte(), WriteWord() and Close(). If you want to rewrite
          GIFSAVE to use other file I/O than streams, you need only change
          theese functions.










          GIFSAVE reference                                       PAGE 4




                                      THE FUNCTIONS
                                      =============


          GIF_Create()

                  Function  Creates a new GIF-file, and stores info on the
                            screen.

                    Syntax  int GIF_Create(
                                    char *filename,
                                    int width, int height,
                                    int numcolors, int colorres
                                );

                   Remarks  Creates a new (or overwrites an existing)
                            GIF-file with the given filename. No
                            .GIF-extension is added.

                            The width- and height- parameters specifies the
                            size of the screen.

                            numcolors is the number of colors used in the
                            image.

                            colorres is number of bits used to encode a
                            primary color (red, green or blue). In GIF-files,
                            colors are built by combining given amounts of
                            each primary color. On VGA-cards, each color is
                            built by combining red, green and blue values in
                            the range [0, 63]. Encoding the number 63 would
                            require 6 bits, so colorres would be set to 6.

              Return value  GIF_OK        - OK
                            GIF_ERRCREATE - Error creating file
                            GIF_ERRWRITE  - Error writing to file
                            GIF_OUTMEM    - Out of memory











          GIFSAVE reference                                       PAGE 5




          GIF_SetColor()

                  Function  Specifies the primary color component of a color
                            used in the image.

                    Syntax  void GIF_SetColor(
                                     int colornum,
                                     int red, int green, int blue
                                 );

                   Remarks  This function updates the colortable-values for
                            color number colornum in the image.

                            Should be called for each color in the range

                                [0, numcolors]

                            with red, green and blue components in the range

                                [0, (1 << colorres) - 1]

                            colorres and colornum are values previousely
                            given to the function GIF_Create().

              Return value  None










          GIFSAVE reference                                       PAGE 6




          GIF_CompressImage()

                  Function  Compresses an image and stores it in the current
                            file.

                    Syntax  int GIF_CompressImage(
                                    int left, int top,
                                    int width, int height,
                                    int (*getpixel)(int x, int y)
                                );

                   Remarks  The left- and top- parameters indicate the image
                            offset from the upper left corner of the screen.
                            They also give the start values for calls to the
                            userdefined callback function.

                            width and height give the size of the image. A
                            value of -1 indicates the equivalent screen size
                            given in the call to GIF_Create().

                            If the image is supposed to cover the entire
                            screen, values 0, 0, -1, -1 should be given.

                            GIF_CompressImage() obtains the pixel values by
                            calling a user specified function. This function
                            is passed in the parameter getpixel. See "THE
                            CALLBACK FUNCTION" further down for a description
                            of this function.

              Return value  GIF_OK        - OK
                            GIF_ERRWRITE  - Error writing to file
                            GIF_OUTMEM    - Out of memory











          GIFSAVE ref